home *** CD-ROM | disk | FTP | other *** search
/ Ham Radio 2000 / Ham Radio 2000.iso / ham2000 / satellit / kissfilt / kissfilt.doc < prev    next >
Text File  |  1991-04-22  |  9KB  |  196 lines
  1. KISSFILT - A Tool for Filtering the Contents of KISS Log Files
  2.  
  3. April 22, 1991
  4.  
  5. Copyright 1991 Paul Williamson, KB5MU
  6. You may use this program for non-commercial purposes, and you may
  7. distribute complete copies freely.
  8.  
  9. KISSFILT allows you to remove unwanted packets from your KISS log files.
  10. For example, if you copy a pass of AMSAT-OSCAR 16 using the broadcast
  11. protocol receiver program PB, you end up with a KISS log file containing
  12. every frame received during the pass (other than the broadcast data
  13. frames themselves).  This file will contain telemetry from the satellite,
  14. data frames sent from the satellite to other users, acknowledgements sent
  15. by the satellite to other users, and various other stuff.  Suppose you
  16. want to archive telemetry from AO-16.  If you store the KISS log file
  17. PB created, you will be storing lots of useless stuff.  Unless you use
  18. KISSFILT first.
  19.  
  20. KISSFILT provides two basic types of filtering.  It can filter by source
  21. and destination callsigns, or it can filter out all non-information
  22. frames.  The callsign filter is by far the more complex and powerful
  23. of the two features.  Most of this document will be devoted to an
  24. explanation of how to use the callsign filter.
  25.  
  26. KISSFILT is invoked from the DOS command line.  You provide the input
  27. and output file names on the command line, as follows:
  28.  
  29.     C:> kissfilt filename.kss filename.out
  30.  
  31. If that's all you provide, KISSFILT will drop into an interactive mode.
  32. It will scan through the input file, frame by frame, interpreting the
  33. KISS format.  For each frame, it extracts the source and destination
  34. callsigns.  For each new pair of callsigns, KISSFILT asks you whether
  35. you want to Keep or Discard frames from that source to that destination.
  36. You respond by hitting the K key for keep or the D key for discard.
  37. You may also hit the Q key for quit, which will end the program without
  38. processing that frame or any later frame.  If you say Keep, KISSFILT
  39. copies the frame to the output file.  If you say Discard, it just goes
  40. on to the next frame without copying the current frame to the output
  41. file.  When you tell KISSFILT what to do with a frame, it remembers
  42. your answer and automatically does the same thing with all other frames
  43. from that source to that destination.
  44.  
  45. As you might imagine, answering all those prompts can get quite tedious,
  46. especially if you know exactly what frames you want to keep and which
  47. you want to discard before you start.  In that case, you can put your
  48. decisions in a "filter file".  You specify the filter file on the DOS
  49. command line after the output file:
  50.  
  51.     C:> kissfilt filename.kss filename.out filtfile.ext
  52.  
  53. The filter file can contain various commands.  Each command must be on
  54. a separate line.  Blank lines are OK, and you can put comments in the
  55. file by starting the line with a semicolon (";").  The following
  56. commands are accepted:
  57.  
  58.     Command Format        Meaning 
  59.     ==============        =======
  60.     keep call1 call2    Keep frames from call1 to call2
  61.     discard call1 call2    Discard frames from call1 to call2
  62.     ask call1 call2        Ask about frames from call1 to call2
  63.     else keep        Keep any frames not matched
  64.     else discard        Discard any frames not matched
  65.     else ask        Ask about any frames not matched
  66.     info-only        Discard any non-information frames
  67.  
  68. In the Keep, Discard, and Ask commands, the callsign fields may simply
  69. contain callsigns, or they may contain what's called a "regular
  70. expression" specifying a pattern for what callsigns are to be matched.
  71. Regular expressions are like wildcards, only more powerful.  For this
  72. application, they're probably more powerful than necessary, but I had
  73. a regular expression matching routine (written by Henry Spencer) handy,
  74. so I threw it in.  Henry Spencer's description of regular expressions
  75. in included as RE.DOC in the archive.  Unfortunately, it's written for
  76. computer scientists; if you're not familiar with formal languages, you
  77. may have trouble understanding his description.  I'll just describe a
  78. simple subset of the language, and that'll probably be all you need.
  79.  
  80. Rule 1:    If you don't want to mess with fancy pattern matching, you can
  81. just ignore it.  Just put callsigns in the callsign fields.
  82. Examples:
  83.     LUSAT-1        matches        LUSAT-1 (and nothing else)
  84.     KB5MU        matches        KB5MU (and nothing else)
  85.     KB5MU-0        matches        nothing, since KB5MU-0 is KB5MU
  86.  
  87. Rule 2:  A dot ('.') matches any single character.  It works like a
  88. question mark in DOS.
  89. Examples:
  90.     KB.MU        matches        KB5MU, KB1MU, KBxMU, etc.
  91.     ...        matches        ABC, XYZ, 4U1, etc.
  92.  
  93. Rule 3: Anything followed by an asterisk ('*') matches any number of
  94. that thing, including zero.
  95. Examples:
  96.     KB*MU        matches        KMU, KBMU, KBBMU, KBBBMU, etc.
  97.     K.*MU        matches        KMU, KxMU, KxyMU, KxyzMU, etc.
  98.  
  99. That last examples is particularly important.  The sequence ".*" means
  100. "zero or more of any character".  That description matches any string.
  101. It's like the way "*" works in DOS.  Let's look at more examples of
  102. that technique:
  103.     .*        matches        absolutely anything
  104.     K.*        matches        anything that starts with K
  105.     KB5MU-.*    matches        KB5MU-1, KB5MU-15, etc.
  106.     .*5.*        matches        anything with a 5 in it.
  107.     .*-.*        matches        anything with a nonzero SSID
  108.  
  109. That's all you need to know about regular expressions.  If you want to
  110. experiment with the more powerful expression matching capabilities of
  111. KISSFILT, consult RE.DOC.
  112.  
  113.  
  114. Let's take a look at an example filter file:
  115.  
  116.     keep PACSAT-1 TLM
  117.     keep PACSAT-1 TIME
  118.     ask PACSAT-1 .*
  119.     else discard
  120.  
  121. This is a typical filter file you might use to reduce the size of a
  122. telemetry archive from AO-16.  The first line, "keep PACSAT-1 TLM" says
  123. that KISSFILT is to keep any frames addressed from PACSAT-1 to TLM.
  124. These are the telemetry frames you want.  The second line, "keep PACSAT-1
  125. TIME" says that you also want to keep the time frames.  The third line,
  126. "ask PACSAT-1 .*" matches any frame addressed from PACSAT-1 to any
  127. address.  It tells KISSFILT that you want it to ask you about any frames
  128. from PACSAT-1.  Now frames from PACSAT-1 to TLM or TIME are already kept,
  129. according to lines 1 and 2.  The earlier line rules, so line 3 actually
  130. matches any frame addressed from PACSAT-1 to any address *other than* the
  131. ones already specified.  The last line, "else discard", tells KISSFILT
  132. that you aren't interested in any frames that don't match any of the
  133. other lines.  In this case, any packet with a source address other than
  134. PACSAT-1 will be discarded.
  135.  
  136. For another example, suppose you don't know what callsigns are in the
  137. file.  You could run a program to translate the KISS file into an ASCII
  138. file (my program KISS2ASC, for instance), then go through the file with
  139. a text editor, and make up a filter file containing the instructions.
  140. Or, you could let KISSFILT do the work by using the following filter
  141. file:
  142.     else ask
  143. That one-line filter file says that you want KISSFILT to ask you about
  144. every source+destination callsign pair it finds in the file.  Even
  145. simpler, just don't use a filter file at all, since this is KISSFILT's
  146. default behavior.
  147.  
  148. For yet another example, suppose you want to see just the information
  149. packets typed by users.  You don't want to see the packets sent by the
  150. satellite, and you don't care about the acknowledgement and other
  151. overhead packets sent by the users either.  This filter file does just
  152. that:
  153.     discard PACSAT.* .*
  154.     else keep
  155.     info-only
  156. That last line, "info-only", is the key to eliminating the acknowledgement
  157. and other link overhead packets.  With info-only specified, only frames
  158. with type I (information, used by connected stations), UI (unnumbered
  159. information, used for broadcasts, CQs, and roundtables), and FRMR (frame
  160. reject, which contains reject-reason information) are copied into the
  161. output file.  All other frames are discarded.
  162.  
  163. That's all there is to it!
  164.  
  165. ===================================================================
  166. This release of KISSFILT is the first version to leave my shack.
  167. As usual, that means it probably has bugs.  If you find any bugs, please
  168. let me know.  If you have suggestions for improvements, please let me
  169. know.  If you find KISSFILT useful, it wouldn't hurt to let me know that,
  170. too.
  171.  
  172. Source code is available on request.  KISSFILT is written in C, for the
  173. Microsoft version 6.00a compiler.  There are only a couple of compiler
  174. specific things in the code, so it should be quite easy to compile
  175. KISSFILT on other compilers or for other (command-line oriented) machines.
  176.  
  177. The regular expression matching routines were written by Henry Spencer,
  178. and are Copyright (c) 1986 by University of Toronto.  He has granted
  179. to anyone permission to use the routines, and for that I thank him.
  180. The rest of KISSFILT is either derived from my earlier program KISS2ASC,
  181. or hacked up in a couple of late nights.
  182.  
  183. I can be contacted by any of the following means.  If you use paper mail
  184. and expect a reply, please enclose an SASE.
  185.  
  186.         73  -Paul Williamson, KB5MU
  187.  
  188.  
  189. Pacsat:        KB5MU via AO-16 or LO-19
  190. Packet BBS:    KB5MU @ AA6QN.#SOCA.CA.USA (or whatever they're using today)
  191. Compu$erve:    75265,367
  192. Internet:    pwilliamson@drzeus.qualcomm.com
  193. Paper mail:    5331 Channing Street
  194.         San Diego, CA  92117-3206
  195.  
  196.